Версия: 1.7.5

Описание модуля (core-description.yaml)

Помимо runtime-конфига (config.yaml), у каждого модуля есть файл описания — core-description.yaml. Он определяет:

Метаданные модуля (имя, версия, Docker-образ)
configTemplate — YAML-схему, по которой фронтенд рисует UI-форму настройки модуля

Структура файла

# config/core-description.yaml
version: 0.1

moduleName: "Модуль сетевого сканирования Nmap"
moduleVersion: "0.1.2"
moduleDescription: "Сканирование сети с помощью nmap"
moduleConfidence: 20
moduleConfidenceForce: false
moduleManagerVersion: "0.1"
imageUrl: "registry.lighthouse.rt-solar.ru/lighthouse/modules/nmap-module"

configTemplate:
  - GroupName: "Настройка модуля Nmap"
    GroupKey: "main"
    Fields:
      - FieldKey: "hostIps"
        FieldName: "Цель сканирования"
        FieldType: "String"
        FieldRegex: ".*"
        FieldDescription: "IP адрес, сеть или доменное имя"
        FieldDefaultValue: "{{allNetworks.cidr.bySpace}}"
        FieldRequired: true

Поля метаданных модуля

Поле	Тип	Описание
`version`	string	Версия формата файла описания
`moduleName`	string	Отображаемое имя модуля в UI
`moduleVersion`	string	Версия модуля (семвер)
`moduleDescription`	string	Описание модуля для UI
`moduleConfidence`	int	Уровень доверия к данным модуля (0-100)
`moduleConfidenceForce`	bool	Принудительно применять confidence
`moduleManagerVersion`	string	Совместимая версия Keeper
`imageUrl`	string	URL Docker-образа в registry

configTemplate -- схема UI-формы

configTemplate — это массив групп полей. Каждая группа отображается как отдельная секция в интерфейсе настройки модуля.

Структура группы

Поле	Тип	Описание
`GroupKey`	string	Уникальный ключ группы (используется как ключ в config.yaml при запуске)
`GroupName`	string	Заголовок группы в UI
`Fields`	array	Массив полей формы

Структура поля (Field)

Поле	Тип	Обязательное	Описание
`FieldKey`	string	да	Ключ поля (передаётся в config.yaml модуля при запуске)
`FieldName`	string	да	Лейбл в UI
`FieldType`	string	да	Тип поля: `String`, `Number`, `Bool`, `TextArea`
`FieldDescription`	string	да	Подсказка / tooltip в UI
`FieldDefaultValue`	any	да	Значение по умолчанию
`FieldRegex`	string	да	Regex для валидации ввода (например `".*"` — любое значение)
`FieldRequired`	bool	да	Обязательное ли поле

Типы полей (FieldType)

FieldType	Описание	Пример значения
`String`	Однострочный текстовый ввод	`"192.168.1.0/24"`
`Number`	Числовой ввод	`1433`
`Bool`	Чекбокс (вкл/выкл)	`true` / `false`
`TextArea`	Многострочный текстовый ввод	JSON-объект, SQL-запрос

Плейсхолдеры в FieldDefaultValue

В значениях по умолчанию можно использовать динамические плейсхолдеры. Keeper подставляет реальные значения перед запуском модуля:

Плейсхолдер	Описание
`{{allNetworks.cidr.bySpace}}`	Все CIDR сетей текущей зоны через пробел
`{{host.ip}}`	IP-адрес текущего хоста (для модулей, запускаемых на конкретном хосте)

Секреты (Vault) в FieldDefaultValue

Для паролей и токенов используйте синтаксис [[KEY]] — Keeper подставит значение из Vault:

- FieldKey: "password"
  FieldName: "Пароль"
  FieldType: "String"
  FieldDefaultValue: "[[secret_name_for_db]]"
  FieldRequired: true

Пользователь в UI увидит [[secret_name_for_db]] как дефолтное значение и может заменить его на имя своего секрета из Vault.

Полный пример -- модуль с несколькими группами

configTemplate:
  # Группа 1: параметры подключения
  - GroupName: "Настройка подключения"
    GroupKey: "auth"
    Fields:
      - FieldKey: "host"
        FieldName: "Адрес сервера"
        FieldType: "String"
        FieldRegex: ".*"
        FieldDescription: "IP-адрес или FQDN сервера"
        FieldDefaultValue: "10.10.10.10"
        FieldRequired: true

      - FieldKey: "port"
        FieldName: "Порт"
        FieldType: "Number"
        FieldRegex: ".*"
        FieldDescription: "Порт для подключения"
        FieldDefaultValue: 1433
        FieldRequired: true

      - FieldKey: "user"
        FieldName: "Имя пользователя"
        FieldType: "String"
        FieldRegex: ".*"
        FieldDescription: "Учётная запись для подключения"
        FieldDefaultValue: ""
        FieldRequired: true

      - FieldKey: "password"
        FieldName: "Пароль"
        FieldType: "String"
        FieldRegex: ".*"
        FieldDescription: "Для хранения пароля рекомендуем использовать Секреты"
        FieldDefaultValue: "[[secret_name]]"
        FieldRequired: true

      - FieldKey: "ssl"
        FieldName: "SSL соединение"
        FieldType: "Bool"
        FieldRegex: ".*"
        FieldDescription: "Использовать защищённое подключение"
        FieldDefaultValue: true
        FieldRequired: true

  # Группа 2: выбор типов данных
  - GroupName: "Типы получаемых данных"
    GroupKey: "data_types"
    Fields:
      - FieldKey: "collect_hosts"
        FieldName: "Хосты"
        FieldType: "Bool"
        FieldDescription: "Получать хосты"
        FieldDefaultValue: true
        FieldRequired: true

      - FieldKey: "collect_software"
        FieldName: "Программное обеспечение"
        FieldType: "Bool"
        FieldDescription: "Получать информацию о ПО"
        FieldDefaultValue: true
        FieldRequired: true

  # Группа 3: дополнительные поля с TextArea
  - GroupName: "Дополнительная метадата"
    GroupKey: "optional-fields"
    Fields:
      - FieldKey: "additional_fields"
        FieldName: "Маппинг полей в метадату"
        FieldType: "TextArea"
        FieldRegex: ".*"
        FieldDescription: "Укажите поля в формате JSON: {\"source_field\":\"metadata_field\"}"
        FieldDefaultValue: "{\"cn\":\"CN\",\"badPwdCount\":\"bad_pwd_count\"}"
        FieldRequired: false

Как configTemplate попадает в систему

Разработчик создаёт config/core-description.yaml в репозитории модуля
При регистрации модуля (через API или seed) содержимое configTemplate сохраняется в таблицу modules (поле config_template, тип TEXT) как YAML-строка
Фронтенд читает configTemplate и рисует UI-форму
Пользователь заполняет форму, значения сохраняются в конфигурацию запуска
При запуске модуля Keeper собирает config.yaml из заполненных значений, подставляет секреты из Vault и плейсхолдеры, монтирует файл в контейнер

Связь configTemplate и config.yaml

configTemplate определяет какие поля покажет UI. Заполненные пользователем значения Keeper соберёт в config.yaml, который получит модуль:

configTemplate (UI-схема)          ->  config.yaml (runtime)
-------------------------------    -------------------------
GroupKey: "auth"                      auth:
  FieldKey: "host" = "10.0.0.1"        host: "10.0.0.1"
  FieldKey: "port" = 5432              port: 5432
  FieldKey: "password" = "[[pw]]"      password: "реальный-пароль-из-vault"
GroupKey: "data_types"                data_types:
  FieldKey: "collect_hosts" = true      collect_hosts: true

В коде модуля эти значения доступны через Pydantic-конфиг (см. секцию 4).

Структура файла​

Поля метаданных модуля​

configTemplate -- схема UI-формы​

Структура группы​

Структура поля (Field)​

Типы полей (FieldType)​

Плейсхолдеры в FieldDefaultValue​

Секреты (Vault) в FieldDefaultValue​

Полный пример -- модуль с несколькими группами​

Как configTemplate попадает в систему​

Связь configTemplate и config.yaml​